<div class="sect3">
<h4 id="options"><a class="anchor" href="#options"></a>options<a class="anchorjs-link " href="#options" aria-label="Anchor link for: options" data-anchorjs-icon="" style="font: 1em/1 anchorjs-icons; padding-left: 0.375em;"></a></h4>
<div class="paragraph">
<p>The <code>options</code> directive allows configuring Pipeline-specific options from
within the Pipeline itself. Pipeline provides a number of these options, such
as <code>buildDiscarder</code>, but they may also be provided by plugins, such as
<code>timestamps</code>.</p>
</div>
<table class="tableblock frame-all grid-all stretch syntax">
<colgroup>
<col style="width: 10%;">
<col style="width: 90%;">
</colgroup>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Required</p></th>
<td class="tableblock halign-right valign-top"><div class="content"><div class="paragraph">
<p>No</p>
</div></div></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Parameters</p></th>
<td class="tableblock halign-right valign-top"><div class="content"><div class="paragraph">
<p><em>None</em></p>
</div></div></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Allowed</p></th>
<td class="tableblock halign-right valign-top"><div class="content"><div class="paragraph">
<p>Only once, inside the <code>pipeline</code> block.</p>
</div></div></td>
</tr>
</tbody>
</table>
<div class="sect4">
<h5 id="available-options"><a class="anchor" href="#available-options"></a>Available Options<a class="anchorjs-link " href="#available-options" aria-label="Anchor link for: available options" data-anchorjs-icon="" style="font: 1em/1 anchorjs-icons; padding-left: 0.375em;"></a></h5>
<div class="dlist">
<dl>
<dt class="hdlist1">buildDiscarder</dt>
<dd>
<p>Persist artifacts and console output for the specific number
of recent Pipeline runs. For example: <code>options { buildDiscarder(logRotator(numToKeepStr: '1')) }</code></p>
</dd>
<dt class="hdlist1">checkoutToSubdirectory</dt>
<dd>
<p>Perform the automatic source control checkout
in a subdirectory of the workspace. For example: <code>options { checkoutToSubdirectory('foo') }</code></p>
</dd>
<dt class="hdlist1">disableConcurrentBuilds</dt>
<dd>
<p>Disallow concurrent executions of the Pipeline. Can
be useful for preventing simultaneous accesses to shared resources, etc. For
example: <code>options { disableConcurrentBuilds() }</code></p>
</dd>
<dt class="hdlist1">newContainerPerStage</dt>
<dd>
<p>Used with <code>docker</code> or <code>dockerfile</code> top-level
agent. When specified, each stage will run in a new container instance
on the same node, rather than all stages running in the same container instance.</p>
</dd>
<dt class="hdlist1">overrideIndexTriggers</dt>
<dd>
<p>Allows overriding default treatment of branch indexing triggers.
If branch indexing triggers are disabled at the multibranch or organization label, <code>options { overrideIndexTriggers(true) }</code>
will enable them for this job only. Otherwise, <code>options { overrideIndexTriggers(false) }</code> will
disable branch indexing triggers for this job only.</p>
</dd>
<dt class="hdlist1">preserveStashes</dt>
<dd>
<p>Preserve stashes from completed builds, for use with
stage restarting. For example: <code>options { preserveStashes() }</code> to
preserve the stashes from the most recent completed build, or <code>options
{ preserveStashes(5) }</code> to preserve the stashes from the five most
recent completed builds.</p>
</dd>
<dt class="hdlist1">retry</dt>
<dd>
<p>On failure, retry the entire Pipeline the specified number of times.
For example: <code>options { retry(3) }</code></p>
</dd>
<dt class="hdlist1">skipDefaultCheckout</dt>
<dd>
<p>Skip checking out code from source control by default in
the <code>agent</code> directive. For example: <code>options { skipDefaultCheckout() }</code></p>
</dd>
<dt class="hdlist1">skipStagesAfterUnstable</dt>
<dd>
<p>Skip stages once the build status has gone to UNSTABLE. For example: <code>options { skipStagesAfterUnstable() }</code></p>
</dd>
<dt class="hdlist1">timeout</dt>
<dd>
<p>Set a timeout period for the Pipeline run, after which Jenkins should
abort the Pipeline. For example: <code>options { timeout(time: 1, unit: 'HOURS') }</code></p>
</dd>
<dt class="hdlist1">timestamps</dt>
<dd>
<p>Prepend all console output generated by the Pipeline run with the
time at which the line was emitted. For example: <code>options { timestamps() }</code></p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="options-example"><a class="anchor" href="#options-example"></a>Example<a class="anchorjs-link " href="#options-example" aria-label="Anchor link for: options example" data-anchorjs-icon="" style="font: 1em/1 anchorjs-icons; padding-left: 0.375em;"></a></h5>
<div class="pipeline-block">  <div class="listingblock pipeline-declarative">
    <div class="title">Jenkinsfile (Declarative Pipeline)</div>
    <div class="content">
  <pre class="CodeRay highlight nowrap"><code class="language-groovy" data-lang="groovy">pipeline {
    agent any
    options {
        timeout(<span style="color:#606">time</span>: <span style="color:#00D">1</span>, <span style="color:#606">unit</span>: <span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">'</span><span style="color:#D20">HOURS</span><span style="color:#710">'</span></span>) <span style="color:#777"><i class="conum" data-value="1"></i><b>(1)</b></span>
    }
    stages {
        stage(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">'</span><span style="color:#D20">Example</span><span style="color:#710">'</span></span>) {
            steps {
                echo <span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">'</span><span style="color:#D20">Hello World</span><span style="color:#710">'</span></span>
            }
        }
    }
}</code></pre>
</div></div></div>
<div class="colist arabic">
<table>
<tbody><tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>Specifying a global execution timeout of one hour, after which Jenkins will
abort the Pipeline run.</td>
</tr>
</tbody></table>
</div>
<div class="admonitionblock note">
<table>
<tbody><tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>A comprehensive list of available options is pending the completion of
<a href="https://issues.jenkins-ci.org/browse/INFRA-1053">INFRA-1503</a>.</p>
</div>
</td>
</tr>
</tbody></table>
</div>
</div>
<div class="sect4">
<h5 id="stage-options"><a class="anchor" href="#stage-options"></a>stage options<a class="anchorjs-link " href="#stage-options" aria-label="Anchor link for: stage options" data-anchorjs-icon="" style="font: 1em/1 anchorjs-icons; padding-left: 0.375em;"></a></h5>
<div class="paragraph">
<p>The <code>options</code> directive for a <code>stage</code> is similar to the <code>options</code> directive at
the root of the Pipeline. However, the <code>stage</code>-level <code>options</code> can only contain
steps like <code>retry</code>, <code>timeout</code>, or <code>timestamps</code>, or Declarative options that are
relevant to a <code>stage</code>, like <code>skipDefaultCheckout</code>.</p>
</div>
<div class="paragraph">
<p>Inside a <code>stage</code>, the steps in the <code>options</code> directive are invoked before
entering the <code>agent</code> or checking any <code>when</code> conditions.</p>
</div>
<div class="sect5">
<h6 id="available-stage-options"><a class="anchor" href="#available-stage-options"></a>Available Stage Options<a class="anchorjs-link " href="#available-stage-options" aria-label="Anchor link for: available stage options" data-anchorjs-icon="" style="font: 1em/1 anchorjs-icons; padding-left: 0.375em;"></a></h6>
<div class="dlist">
<dl>
<dt class="hdlist1">skipDefaultCheckout</dt>
<dd>
<p>Skip checking out code from source control by default in
the <code>agent</code> directive. For example: <code>options { skipDefaultCheckout() }</code></p>
</dd>
<dt class="hdlist1">timeout</dt>
<dd>
<p>Set a timeout period for this stage, after which Jenkins should
abort the stage. For example: <code>options { timeout(time: 1, unit: 'HOURS') }</code></p>
</dd>
<dt class="hdlist1">retry</dt>
<dd>
<p>On failure, retry this stage the specified number of times.
For example: <code>options { retry(3) }</code></p>
</dd>
<dt class="hdlist1">timestamps</dt>
<dd>
<p>Prepend all console output generated during this stage with the
time at which the line was emitted. For example: <code>options { timestamps() }</code></p>
</dd>
</dl>
</div>
</div>
<div class="sect5">
<h6 id="stage-options-example"><a class="anchor" href="#stage-options-example"></a>Example<a class="anchorjs-link " href="#stage-options-example" aria-label="Anchor link for: stage options example" data-anchorjs-icon="" style="font: 1em/1 anchorjs-icons; padding-left: 0.375em;"></a></h6>
<div class="pipeline-block">  <div class="listingblock pipeline-declarative">
    <div class="title">Jenkinsfile (Declarative Pipeline)</div>
    <div class="content">
  <pre class="CodeRay highlight nowrap"><code class="language-groovy" data-lang="groovy">pipeline {
    agent any
    stages {
        stage(<span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">'</span><span style="color:#D20">Example</span><span style="color:#710">'</span></span>) {
            options {
                timeout(<span style="color:#606">time</span>: <span style="color:#00D">1</span>, <span style="color:#606">unit</span>: <span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">'</span><span style="color:#D20">HOURS</span><span style="color:#710">'</span></span>) <span style="color:#777"><i class="conum" data-value="1"></i><b>(1)</b></span>
            }
            steps {
                echo <span style="background-color:hsla(0,100%,50%,0.05)"><span style="color:#710">'</span><span style="color:#D20">Hello World</span><span style="color:#710">'</span></span>
            }
        }
    }
}</code></pre>
</div></div></div>
<div class="colist arabic">
<table>
<tbody><tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>Specifying a execution timeout of one hour for the <code>Example</code> stage, after
which Jenkins will abort the Pipeline run.</td>
</tr>
</tbody></table>
</div>
</div>
</div>
</div>